Interactive Maintenance

Detailed description of API:

Version & Updates

Version	Revision Date	Revision History
1.0	10th March 2026	New Release

Overview

The interactive maintenance interface is focused on maintenance data for tracking and processing. For each vehicle, only one maintenance plan should be applied, the association of the plan depends on the characteristics and configurations of the vehicle. The plan is reprocessed every day.

Interactive Maintenance Plan within eTim

Notification of Pending Maintenance

Maintenance Info

Walkthrough of Maintenance Procedures

Pre-requisites

Pre-requisites

• Dealer must use their Dealer Portal credentials to authorize API call.
• Each DMS provider will have a subscription_key assigned by CNHi team, please reach out to dlnadmssupport@cnh.com for assistance
• Each Subscription key is unique to DMS and the environment it belongs to
• Based on the payload (XML/JSON), user to pass the content-type in the header

Authentication

Authentication

• DMS will pass Basic auth in HTTP header with username/password
• Each DMS provider will have a subscription_key assigned by CNHi team, please reach out to dlnadmssupport@cnh.com for assistance
• The UserID and Password will be set up in the Dealer Portal by the Dealer uniquely for DMS access to interfaces
• DEP API will require subscription_key in HTTP header to identify client

API Format

• REST

The DEP takes care of the format transformations (as needed) to process the request and provide a response to the DMS system. REST format is always suggested for greater simplicity.

Connection Details

There are a total of 3 APIs for this interface:

• Get Vehicle Telematics Status API
• Get Next Coupons API
• Get Maintenance History by Vin API

CNHi provides both a UAT/Staging and a Production interface for Interactive Maintenance. VINs may be unavailble within staging environment, please reach out to CNHi for VIN examples (if necessary).

Get Vehicle Telematics Status API

The Get Vehicle Telematics API is invoked to verify if the vehicle is connected when there is a next maintenance step alert displayed on eTim.

Environment	URL	API	Request Type
CERT/UAT	https://{base_url}/emeaexternal/services/interactivemaintenance/vehicletelematicsstatus/{VIN}	REST	GET
Production	https://{base_url}/emeaexternal/services/interactivemaintenance/vehicletelematicsstatus/{VIN}	REST	GET

Request Parameters

Note: All Request Query Parameters are case sensitive.

Name	Input	Type	Is Required	Comments
VIN	Template Parameter	String	True	VIN Number

Response Description

Name	Data Type	Description
data	JSON Object
data.vin9	String
data.vin17	String
data.coveredByUcr	Boolean
data.coveredByUcrStatus	Int
data.isConnected	Boolean
data.services	JSON Array (of String)	List of warranties associated to this vehicle.
data.contexts	JSON Array (of String)	This indicates if it is AG or CE
data.telematicsBoxes	JSON Array (of String)	Kind of telematics box installed (PCM, PCMF, AM53, CM1X)
data.modems	JSON Array (of String)	Serial number of the telematics box
data.engineHours	Float
data.lastCommunicationDate	Date Time (nullable)
data.customer	String
data.warrantyStartDate	Date Time (nullable)
data.connectivityStatus	Int (nullable)
data.maintenancePlanStatus	Int (nullable)
data.warrantyStatus	Int (nullable)
data.averageAnnualUsage	Int (nullable)	Average number of engine hours estimated by the dealer for that vehicle. This value is inserted in the service.
data.maintenanceAlertIsActive	Boolean
status	JSON Object
status.code	Int
status.message	String

Sample Response

Download GetVehicleTelematics API Sample Response

Note:

• If the vin is present in UCR but there are no engineHours, you will receive parameters coveredByUcr = true and isConnected = false

• If the vin is present in UCR and there are engineHours, you will receive parameters coveredByUcr = true and isConnected = true

• If the vin isn’t present in UCR and there are no engineHours, you will receive parameters coveredByUcr = false and isConnected = false

Real Value	Covered By UCR	Covered By UCR Status
Covered by UCR	True	0
Not Covered by UCR	False	-1
Expired	False	1
No Transmission	False	2
Inactive	False	3
No Maintenance Plan	False	4

Get Next Coupons API

Note: All Request Query Parameters are case sensitive.

Environment	URL	API	Request Type
CERT/UAT	https://{base_url}/emeaexternal/services/interactivemaintenance/coupons	REST	PUT
Production	https://{base_url}/emeaexternal/services/interactivemaintenance/coupons	REST	PUT

Response Body

Input body parameter, JSON body parameter is given below.

    {
        "vin": "string",
        "isConnected": true,
        "enginehours": 0,
        "language": "string",
        "numberOfbales": 0
    }

Note: Payload (JSON or XML) determined by content-type in the header of the request: Content-Type application/JSON

Response Description

Name	Data Type	Description
data	JSON Object
data.icecode	String
data.plan_id	Int
data.vehicle_next_stop	Float
data.vehicle_delta_overdue_hours	Int
data.vehicle_stop_date	Date Time
data.vehicle_delta_overdue_days	Int
data.contract_number	String
data.contract_start_date	Date Time
data.contract_end_date	Date Time
data.warranty_type	String
data.warranty_start_date	Date Time
data.is_optimized	Boolean
data.vehicleNextStopBales	Int	Closest next stop for coupon in bales
data.vehicleDeltaOverdueBales	Int	Number of overdue bales
data.applicable_mission_list	JSON Array
data.applicable_mission_list.id	Int
data.applicable_mission_list.description	String
data.applicable_mission_list.plan_id	Int
data.nextCoupons	JSON Array
data.nextCoupons.last_engh	Float
data.nextCoupons.numberOfBales	Int	Current number of bales
data.nextCoupons.day	Date Time
data.nextCoupons.last_maintenance_step	Int
data.nextCoupons.next_maintenance_step	Int
data.nextCoupons.maintenance_type	String
data.nextCoupons.description	String
data.nextCoupons.next_maintenance	Int
data.nextCoupons.next_maintenance_desc	String
data.nextCoupons.hours_in_overdue	Int
data.nextCoupons.is_high_overdue	Boolean
data.nextCoupons.is_coupon_next_stop	Boolean
data.nextCoupons.days_in_overdue	Int
data.nextCoupons.is_high_overdue_days	Boolean
data.nextCoupons.forecast_in_hours	Float
data.nextCoupons.is_forecast_in_tolerance_hours	Boolean
data.nextCoupons.forecast_in_days	Int
data.nextCoupons.is_forecast_in_tolerance_months	Boolean
data.nextCoupons.working_units	Int
data.nextCoupons.defect_code	String
data.nextCoupons.is_hidden	Boolean
data.nextCoupons.nextMaintenanceStepBales	Int
data.nextCoupons.balesInOverdue	Int
data.nextCoupons.forecastInBales	Int
data.nextCoupons.isHighOverdueBales	Int
data.nextCoupons.isForecastInToleranceBales	Boolean
data.nextCoupons.operations	JSON Array
data.nextCoupons.operations.code	String
data.nextCoupons.operations.description	String
data.nextCoupons.operations.desc_series	String
data.nextCoupons.operations.location	String
data.nextCoupons.operations.location_description	String
data.nextCoupons.operations.type_description	String
data.nextCoupons.operations.parts	JSON Array
data.nextCoupons.operations.parts.part_number	String
data.nextCoupons.operations.parts.description	String
data.nextCoupons.operations.parts.second_desc	String
data.nextCoupons.operations.parts.quantity	Float
data.nextCoupons.operations.parts.is_kit	Boolean
data.nextCoupons.operations.parts.group	Int
data.nextCoupons.operations.consumables	JSON Array
data.nextCoupons.operations.consumables.cons_id	Int
data.nextCoupons.operations.consumables.occurrence_id	Int
data.nextCoupons.operations.consumables.technical_characteristic	String
data.nextCoupons.operations.consumables.description	String
data.nextCoupons.operations.consumables.second_desc	String
data.nextCoupons.operations.consumables.part_number	String
data.nextCoupons.operations.consumables.quantity	Float
data.nextCoupons.operations.consumables.unit	String
data.nextCoupons.operations.consumables.quantity_uk	Float
data.nextCoupons.operations.consumables.unit_uk	String
status	JSON Object
status.code	Int
status.message	String

Sample Response

Download GetNextCoupons API Sample Response

Output Values

next_maintenance and next_maintenance_desc output values:

next_maintenance	next_maintenance_desc
0	Coupon history
1	Coupon in Tolerance Engine Hours
2	Coupon in Tolerance Next Stop
3	Alert
4	Overdue

Get Maintenance History by VIN API

This API query is initiated by passing the VIN number, and the code language (refer to appendix) of the vehicle. It retrieves all the relevant information for maintenance history along with the details of all applied coupons (currently in eTim).

Environment	URL	API	Request Type
CERT/UAT	https://{base_url}/emeaexternal/services/interactivemaintenance/maintenancehistorybyvin/{VIN}	REST	GET
Production	https://{base_url}/emeaexternal/services/interactivemaintenance/maintenancehistorybyvin/{VIN}	REST	GET

Request Parameters

Note: All Request Query Parameters are case sensitive.

Name	Input	Type	Is Required	Comments
VIN	Template Parameter	String	True	VIN Number
lang	Query Parameter	Char	False	Contains the code language

Response Description

Name	Data Type
data	JSON Object
data.vin	String
data.maintenanceServicesHistoryList	JSON Array
data.maintenanceServicesHistoryList.maintenanceServiceDate	Date Time
data.maintenanceServicesHistoryList.serviceEngineHours	Float
data.maintenanceServicesHistoryList.maintenanceSaveDate	Date Time
data.maintenanceServicesHistoryList.telematicsEngineHours	Float
data.maintenanceServicesHistoryList.planId	Int
data.maintenanceServicesHistoryList.comments	String
data.maintenanceServicesHistoryList.theoreticalEngineHours	Float
data.maintenanceServicesHistoryList.theoreticalDate	Date Time
data.maintenanceServicesHistoryList.platform	String
data.maintenanceServicesHistoryList.userType	String
data.maintenanceServicesHistoryList.dealerCode	String
data.maintenanceServicesHistoryList.numberOfBales	Int
data.maintenanceServicesHistoryList.maintenanceTypeList	JSON Array
data.maintenanceServicesHistoryList.maintenanceTypeList.maintenanceType	String
data.maintenanceServicesHistoryList.maintenanceTypeList.workingUnits	String
data.maintenanceServicesHistoryList.maintenanceTypeList.description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations	JSON Array
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.code	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.descriptionSeries	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.location	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.location_description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.type_description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.parts	JSON Array
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.parts.partNumber	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.parts.description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.parts.secondDescription	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.parts.original	Boolean
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.consumables	JSON Array
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.consumables.consId	Int
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.consumables.occurrenceId	Int
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.consumables.description	String
data.maintenanceServicesHistoryList.maintenanceTypeList.operations.consumables.partNumber	String
status	JSON Object
status.code	Int
status.message	String

Sample Response

Download GetMaintenanceHistoryByVin API Sample Response

Response Codes

Title	Reason	Code
REST success response	Success	200
REST failure response	Authentication Error: Access denied due to missing credentials!	401
REST failure response	Internal Server Error	500
REST failure response	Bad Request	400